.NET Software Development Kit (SDK): 
Developing Applications Using the USPS 
Service Delivery Extensions 


Last Modified: September 14, 2021 


1 


.NET Software Development Kit OvervieW sese esse eee eee eee eee 4 
1.1 Licensesiand Lab T 4 
1.2 PUTOS TT 4 
1.3 Contacto mati Ai A 4 

Application Programming Interface (API... eee eee 5 
2.1 ErrorMessageDictionary Class ........ccccocononocoonnonnnnnnnnnonnnnnnnnncnnnonononnnnnnnnnnnnnnnnonnnoss 5 

ZA NAMES PACA A A A A O lada 5 

A s G e TTT 5 
2.2 ExpressMailGuaranteed Cla SS nea a a a e a 5 

2:21” V Tnne e H a a ria 5 

2:2:2. BAS Si A A TUTE E E AE 5 
2.3 ExpressMailGuaranteedltem Class sees 5 

2:3:1: “NAMOS PAC rrain NN NN 5 

232 <T eT 5 

21323" O TN 5 
2.4 ExpressMailGuaranteedltemCollection Cass... sees 5 

24:1. Namespace ini 5 

DAD Base Clis Sioni na aaa cou a aa 5 
2.5 GCWrapperFormatter Clas Sisareni krn aa a e a a isai 6 

2:5:1: Namespace creci titi ir 6 

ET C RS 6 

2.5.3 ToGetStatesAndProvinces Method... sese 6 

2.54. TOGStGities MODO dai il tds 6 

2.5.5 ToGetPostCodesForDestination Method... sss sese eee 7 

2.5.6 ToGetCitiesAndStatesOrProvincesCodeForThisPostalCodeUsingPostingDate 

Method ata dto 8 

2.5.7 ToGetGDlUsingPostcodes Method... ss sss eee 8 

2.5.8 TolsValidHolidayByProductType Method... sss sese 9 
2.6 KPGEXCEDLION Casa A ci 10 

ZO Namespace iii anio 10 

262. Base as AA AEAEE Aea I a TARA 10 
2.7 OnlineServiceCommitment Class... sss sese eee eee eee 10 

2:7:1. A siniuvesiibeeesesiueussehavteeds sanuyessibeeedsssaa les sayeeeds baaduyesbabenecssdeey 10 

2.72- Base Clas Sicdecat aa EAA A EAO EEEa E a AR AERES 10 

LS Properties: soinn aaeoa aaa A Ad adi 10 
2.8 RequestProperties: Class oil 11 

28L V Tn LT eT Ta A aaa 11 

BB... BASS ClaSS ada daa 11 

278.3 2) eL n 1 S nogi ie cecta seal aieed A a Med ada tae! 11 
2.9 RequestProperties Class oi sy ute 11 

29.1. -Namespace italiana 11 

EE D Te 11 


29.34 O RA 11 


2.10 RequestProperties.RequestLocation Class sees eee eee 12 


210.1 “Namespace. iii ii iia 12 
2AO2° Base las ind lso 12 
LAOS" Propertie S pta 12 
2.11 RequestProperties.RequestLocation Class sees eee 12 
XAT. 1 2 1 aL s (e A A E TET a ae 12 
A O AN 12 
2.12 —ServiceCommitment Class sss esse ee ee ee eee eee 12 
2.1241). NAMES PAC ini A A Asa 12 
212.2 Base Class iii al a 12 
A Properties ona OO 13 
2.12.4- Type: ENUMC@AtlON TTT 13 
2.12.5 Guarantee Enumeration ss sse eee eee eee 14 
2.13 ServiceCommitment.PostalLocation Class... sss eee eee 14 
213E- Namespace ani 14 
213:2 Base Clas ta A A A A A 14 
243:3- 7 geal ca LT sd 14 
2.14 ServiceCommitment.PostalLocationCollection Class sss sese 15 
ZA LO NAMES a tates 15 
ZAAD: BASIC ASS id a Die A dos 15 
2.15 ServiceCommitment Class sss esse eee ee ee eee eee 15 
2.151, ¿Namespace ias 15 
DAS 2 ¡Base Clair dood eaten 15 
2.15.3 Propertie Sinoie tienoin atana aao aaa aaa ATTE RARA E 15 
2:15.1, Type ENUMEAtlon iia ii 15 
2.16  ServiceCommitmentCollection Class sss ss eee 16 
216:1- Namespace lia e 16 
S R SAA > Y ES Classo IED OOOO Tes oaesteisaosian les Se deTetesbaaledetoscteecnaia Ter N 16 
2.16.3  FindByType MethOd....oooooccccccncnonononoonnononnnnnononononnnnnnnnnnnonononnnnnnnnonnnnnnnnnnnnos 16 
2.16.4  FindByMailServiceslID Method... esse 16 
2.17 ServiceCommitmentCollection Class sss sese eee eee 17 
Lodo. ¡NAMES ii tl 17 
217:2 A O O 17 
217.3. - FiIndByType Method oa 17 
2.17.4  FindByMailGroupCode Meth0d.....o.cccccccccnnonococnnonononnnnnononnnnnnnnnconinnnnnonnnnns 18 
DOCUMENT CONTO lia a dial coito 20 


3.1 Amendment G ió 20 


1 .NET Software Development Kit Overview 


This software development kit (SDK) is intended to provide software and Internet 
developers with the ability to integrate postage rate information into programs and/or 
web sites. 


1.1 Licenses and Liability 


The information and components contained within this SDK may be distributed only to 
individuals who have signed the USPS User License and may only be used in accordance 
with the terms of the USPS User License. The USPS assumes no liability for the incorrect 
implementation of this SDK once it has been incorporated into a client product. The 
USPS will supply upgrades to the data and/or the objects when needed, but it assumes 
no part in distribution of these upgrades once the engine has been integrated into client 
products. 


1.2 Purpose 


This document is to be used as a supplement to .NET Software Development Kit 
documentation for the Domestic, International and Business Rate Engines. These 
documents are titled as following: 
e NET Software Development Kit (SDK): Developing Applications Using the USPS 
Domestic Retail Rate Engine 
s NET Software Development Kit (SDK): Developing Applications Using the USPS 
International Retail Rate Engine 
e NET Software Development Kit (SDK): Developing Applications Using the USPS 
Domestic Business Rate Engine 


1.3 Contact Information 


For Technical Support, contact: 


Email: RCalcPEPMOSupport@usps.gov 


For USPS Support, contact USPS: 
Email: PostalExplorer@usps.com 


2 Application Programming Interface (API) 
2.1 ErrorMessageDictionary Class 


2.1.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.International.Entity 


2.1.2 Base Class 
Dictionary<int, string> 


2.2 ExpressMailGuaranteed Class 


2.2.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.International.Entity 


2.2.2 Base Class 


Usps.RateEngine.ServiceDeliveryExtensions.International.Entity.ServiceCommitment 
2.3 ExpressMailGuaranteeditem Class 


2.3.1 Namespace 
Usps.RateEngine.ServiceDeliveryExtensions.International.Entity 


2.3.2 Base Class 


None 


2.3.3 Properties 


Type Description 


Name string The guaranteed name 
Code string The guaranteed code 




















2.4 ExpressMailGuaranteeditemCollection Class 


2.4.1 Namespace 
Usps.RateEngine.ServiceDeliveryExtensions.International.Entity 


2.4.2 Base Class 


List<International.Entity.ExpressMailGuaranteeditem> 


2.5 GCWrapperFormatter Class 


2.5.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.International.Entity 


2.5.2 Base Class 


None 


2.5.3 ToGetStatesAndProvinces Method 


Description 
This method will return a formatted string to request GetStatesAndProvinces from the 
SDC Kahala GCWrapper interface. 


Syntax 
internal string ToGetStatesAndProvinces(string language, string countryCode, DateTime 
postingDate) 


Parameters 
language 
Type: string 


countryCode 
Type: string 


postingDate 
Type: DateTime 


Return Value 
Type: string 


2.5.4 ToGetCities method 


Description 
This method will return a formatted string to request GetCities from the SDC Kahala 
GCWrapper interface. 


Syntax 
internal string ToGetCities(string language, string countryCode, DateTime postingDate, 
bool isOrigin, string stateOrProvinceName) 


Parameters 
language 
Type: string 


countryCode 
Type: string 


postingDate 
Type: DateTime 


isOrigin 
Type: Boolean 


stateorProvinceName 
Type: string 


Return Value 
Type: string 


2.5.5 ToGetPostCodesForDestination Method 


Description 
This method will return a formatted string to request GetPostCodesForDestination from 
the SDC Kahala GCWrapper interface. 


Syntax 
internal string ToGetPostCodesForDestination(string language, string countryCode, 
DateTime postingDate, bool isOrigin, string stateOrProvinceName, string cityName) 


Parameters 
language 


Type: string 


countryCode 
Type: string 


postingDate 
Type: DateTime 


isOrigin 
Type: Boolean 


stateorProvinceName 
Type: string 


cityName 
Type: string 


Return Value 


Type: string 


2.5.6 ToGetCitiesAndStatesOrProvincesCodeForThisPostalCodeUsingPos 
tingDate Method 


Description 

This method will return a formatted string to request 
GetCitiesAndStatesOrProvincesCodeForThisPostalCodePostingDate from the SDC Kahala 
GCWrapper interface. 


Syntax 

internal string 
ToGetCitiesAndStatesOrProvincesCodeForThisPostalCodeUsingPostingDate(string 
language, string countryCode, DateTime postingDate, bool isOrigin, string postalCode) 


Parameters 
language 
Type: string 


countryCode 
Type: string 


postingDate 
Type: DateTime 


isOrigin 
Type: Boolean 


postalCode 
Type: string 


Return Value 
Type: string 


2.5.7 ToGetGDIUsingPostcodes Method 


Description 
This method will return a formatted string to request GETGDIUsingPostcodes from the 
SDC Kahala GCWrapper interface. 


Syntax 

internal string ToGetGDlUsingPostcodes(string language, string countryCode, DateTime 
postingDate, string productType, string postalCode, string destinationLanguageCode, 
string destinationCountryCode, string destinationPostalCode) 


Parameters 
language 
Type: string 


countryCode 
Type: string 


postingDate 
Type: DateTime 


productType 
Type: string 


postalCode 
Type: string 


destinationLanguageCode 
Type: string 


destinationCountryCode 
Type: string 


destinationPostalCode 
Type: string 


Return Value 
Type: string 


2.5.8 TolsValidHolidayByProductType Method 


Description 
This method will return a formatted string to request IsValidHolidayByproductType from 
the SDC Kahala GCWrapper interface. 


Syntax 
internal string TolsValidHolidayByProductType(string language, string countryCode, 
DateTime holidayDate, string productCode) 


Parameters 
language 
Type: string 


countryCode 
Type: string 


holidayDate 
Type: DateTime 


productCode 
Type: string 


Return Value 
Type: string 


2.6 KPGException Class 


2.6.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.International.Entity 


2.6.2 Base Class 


RateEngineException 
2.7 OnlineServiceCommitment Class 


2.7.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.Domestic.Entity 


2.7.2 Base Class 


Usps.RateEngine.ServiceDeliveryExtensions.Domestic.Entity.ServiceCommitment 


2.7.3 Properties 





























CommitmentName string Gets or sets the commitment 
name. 

CommitmentSequence | string Gets or sets the commitment 
sequence. 

CommitmentTime string Gets or sets the commitment 
time. 

DeliveryDateTime DateTime Gets or sets the delivery date and 
time. 

EstimatedDeliveryTime | string Gets or sets the estimated delivery 
time. 

HoldForPickupLocations | PostalLocationCollection | Gets a reference to a collection of 
postal locations for hold for 
pickup. 

IsHoliday bool Gets or sets a flag that indicates if 
itis a holiday or not. 








Locations PostalLocationCollection | Gets a reference to a collection of 
postal locations. 

















2.8 RequestProperties Class 


2.8.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.Domestic.Entity 


2.8.2 Base Class 


None 


2.8.3 Properties 


Name Type Description 

















Destination RequestLocation The destination 
location 

IDCard IDCard Gets and sets the ID 
card for the request 

MailPieceContents MailPieceContentCollection A collection of mail 
service contents 

Origin RequestLocation The origin location 

Pounds decimal The weight of the mail 
piece in pounds 

ShippingDateTime DateTime The shipping date and 
time. 














2.9 RequestProperties Class 


2.9.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.International.Entity 


2.9.2 Base Class 


None 


2.9.3 Properties 








Description 
Destination RequestLocation The destination 
location 
IDCard IDCard Gets and sets the ID 


card for the request 





MailPieceContents 


MailPieceContentCollection 


A collection of mail 
service contents 





Origin 


RequestLocation 


The origin location 








ShippingDateTime 





DateTime 





The shipping date and 
time. 








2.10 RequestProperties.RequestLocation Class 


2.10.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.Domestic.Entity 


2.10.2 Base Class 


None 


2.10.3 Properties 











Description 
IsPOBox bool Indicates if the 

location is a PO Box 
ZIP ZipCode The ZIP code of the 








location 





2.11 RequestProperties.RequestLocation Class 


2.11.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.International.Entity 


2.11.2 Base Class 
None 


2.12 ServiceCommitment Class 


2.12.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.Domestic.Entity 


2.12.2 Base Class 


None 


2.12.3 Properties 








NET IS Type | Description 
ErrorMessage string Gets or sets the error 
message text. 
ErrorNumber int Gets or sets the value 
of the error number. 
Product string Gets or sets the 
product name. 
ServiceCommitmentType ServiceCommitmentType.Type | The type is this 


service commitment. 
See section 2.2.4 
ServiceCommitmentGuarantee | Guarantee Gets or sets service 
commitment 
guarantee. See the 
Guarantee 
enumeration for valid 
values. 
UsedByMailService MailServicelDCollection Gets a reference to a 
collection of mail 
service IDs for the 
mail services that use 
this service 
commitment. 























2.12.4 Type Enumeration 


Name Value Description 








Unknown 0 The service commitment type is unknown. 
ExpressMail 1 The service commitment type is Express Mail. 
PriorityMail 2 The service commitment type is Priority Mail 
FirstClassMail 3 The service commitment type is First Class Mail. 


FirstClassMailLetters | 301 | The service commitment type is First Class Mail Letters. 
FirstClassMailFlats 302 | The service commitment type is First Class Mail Flats. 
FirstClassMailCards | 303 The service commitment type is First Class Mail Cards. 











FirstClassMailPS 304 | The service commitment type is First Class Mail Package 
Service 

StandardMail 4 The service commitment type is Standard Mail. 

Periodicals 5 The service commitment type is periodicals. 

















PackageServices 6 The service commitment type is package services. 





2.12.5 Guarantee Enumeration 


Name Value Description 























Unknown 0 The guarantee type is unknown. 
NoGuarantee 1 The guarantee type is no guarantee. 
MoneyBackGuarantee | 2 The guarantee type is money back. 
LossOnlyGuarantee 3 The guarantee type is lost only. 


2.13 ServiceCommitment.PostalLocation Class 


2.13.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.Domestic.Entity 


2.13.2 Base Class 


None 


2.13.3 Properties 







































































NET IS Type Description 
City string Gets or sets the city of the location. 
CloseTimes string[] Gets or sets an array of close times for the 
location. 

Index Day 

0 Sunday 

1 Monday 

2 Tuesday 

3 Wednesday 

4 Thursday 

5 Friday 

6 Saturday 

7 Holiday 
CutOff string Gets or sets the cutoff time to this location. 
Facility string Gets or sets the facility name. 
FacilitylD string Gets or sets the facility ID. 
ScheduledDeliveryDate | DateTime Gets or sets the scheduled delivery date. 
State string Gets or sets the state of the location. 
Street string Gets or sets the street of the location. 
ZipCode string Gets or sets the ZIP Code of the location. 
ZipCode4 string Gets or sets the ZIP Code+4 of the location. 








2.14 ServiceCommitment.PostalLocationCollection Class 


2.14.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.Domestic.Entity 


2.14.2 Base Class 


List<ServiceCommitment.PostalLocation> 
2.15 ServiceCommitment Class 


2.15.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.International.Entity 


2.15.2 Base Class 


None 


2.15.3 Properties 





























Name Type | Description 

City string Gets and sets the city 

DeliveryDate string 

ErrorMessage string Gets or sets the error message 
text. 

ErrorNumber int Gets or sets the value of the error 
number. 

ServiceCommitmentType | Type The type is this service 
commitment. See section 2.2.4 

ShippingDate DateTime The accepted shipping date 

ShippingTime string The accepted shipping time 

UsedByMailService MailServicelDCollection | Gets a reference to a collection of 
mail service IDs for the mail 
services that use this service 
commitment. 








2.15.1 Type Enumeration 


Name Value Description 


























Unknown 0 The service commitment type is unknown. 

GXG 1 The service commitment type is GXG 
ExpressMail 2 The service commitment type is Express Mail. 
PriorityMail 3 The service commitment type is Priority Mail 
FirstClassMail 4 The service commitment type is First Class Mail. 








ISAL 5 The service commitment type is ISAL. 





Mm 


IPA The service commitment type is IPA. 














MBag 7 The service commitment type is mail bag. 


2.16 ServiceCommitmentCollection Class 


2.16.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.Domestic.Entity 


2.16.2 Base Class 


List<.Domestic.Entity.ServiceCommitment> 


2.16.3 FindByType Method 


Description 
This method is used to find a service commitment in the collection by specifying the 
commitment type. 


Syntax 
public ServiceCommitment FindByType( 
ServiceCommitment.Type type 


) 


public ServiceCommitment FindByType( 
ServiceCommitment.Type type, 
string subType 


Parameters 
type 
Type: ServiceCommitment.Type 
Namespace: ManTech.Usps.RateEngine.Entity 


subType 
Type: string 
Namespace: none 


Return Value 
Type: ServiceCommitment 


2.16.4 FindByMailServicesID Method 
Description 





This method is used to find a service commitment in the collection by specifying the 
mail services ID. 


Syntax 
Public ServiceCommitment FindByMailServicesID( 
MailServicesID mailServicesID 


) 


Parameters 
mailServicesID 
Type: MailServicesID 
NameSpace: ManTech.Usps.RateEngine.Entity 


Return Value 
Type: ServiceCommitment 


2.17 ServiceCommitmentCollection Class 


2.17.1 Namespace 


Usps.RateEngine.ServiceDeliveryExtensions.International.Entity 


2.17.2 Base Class 


List<.International.Entity.ServiceCommitment> 


2.17.3 FindByType Method 


Description 
This method is used to find a service commitment in the collection by specifying the 
commitment type. 


Syntax 
public ServiceCommitment FindByType( 
ServiceCommitment.Type type 


) 


public ServiceCommitment FindByType( 
ServiceCommitment.Type type, 
string subType 


Parameters 


type 
Type: ServiceCommitment.Type 


Namespace: ManTech.Usps.RateEngine.Entity 


subType 
Type: string 
Namespace: none 


Return Value 
Type: ServiceCommitment 


2.17.4 FindByMailGroupCode Method 


Description 
This method is used to find a service commitment in the collection by specifying the 
group code. 


Syntax 
Public ServiceCommitment FindByGroupCode( 
string groupCode 


) 


Parameters 
groupCode 
Type: string 


Return Value 
Type: ServiceCommitment 


3 Document Control 


3.1 Amendment List 


Date Section | Amendment Description Author 





9/14/2021 | 2.12.4 Type | Added 301,302,303,304 for more Austin Naughton 
Enumeration | specific First Class Mail dates. 


